home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / CIncludes / BlockStoragePlugin.h < prev    next >
C/C++ Source or Header  |  1996-05-01  |  43KB  |  1,192 lines
  1. /*
  2.      File:        BlockStoragePlugin.h
  3.  
  4.      Contains:    Block Storage Plug In Programming Interface
  5.  
  6.      Version:    Technology:    Copland
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __BLOCKSTORAGEPLUGIN__
  19. #define __BLOCKSTORAGEPLUGIN__
  20.  
  21. #ifndef __TYPES__
  22. #include <Types.h>
  23. #endif
  24. #ifndef __ERRORS__
  25. #include <Errors.h>
  26. #endif
  27. #ifndef __FILEMANAGERTYPES__
  28. #include <FileManagerTypes.h>
  29. #endif
  30. #ifndef __NAMEREGISTRY__
  31. #include <NameRegistry.h>
  32. #endif
  33. #ifndef __BLOCKSTORAGE__
  34. #include <BlockStorage.h>
  35. #endif
  36. #ifndef __IOMEMORYLISTS__
  37. #include <IOMemoryLists.h>
  38. #endif
  39.  
  40. #ifdef __cplusplus
  41. extern "C" {
  42. #endif
  43.  
  44. #if PRAGMA_IMPORT_SUPPORTED
  45. #pragma import on
  46. #endif
  47.  
  48. #if PRAGMA_ALIGN_SUPPORTED
  49. #pragma options align=power
  50. /* the following contents can only be used by compilers that support PowerPC struct alignment */
  51.  
  52. #if FOR_SYSTEM8_PREEMPTIVE
  53. /*
  54. ******************************************************************************
  55.  *******************************************************************************
  56.  *******************************************************************************
  57.  
  58.     Plug In Constants
  59.     
  60.  *******************************************************************************
  61.  *******************************************************************************
  62.  *****************************************************************************
  63. */
  64. /*
  65. ******************************************************************************
  66.     
  67.     Options to a BSIOFunc
  68.     
  69.  *****************************************************************************
  70. */
  71.  
  72. enum {
  73.     kBSRead                        = 0,
  74.     kBSWrite                    = 1
  75. };
  76.  
  77. /*
  78. ******************************************************************************
  79.  
  80.     Mapping Plug-In Level of Confidence values
  81.     
  82.  *****************************************************************************
  83. */
  84.  
  85. enum {
  86.     kBSMPIDeviceNotSupported    = 0,
  87.     kBSMPIDeviceTypeRecognized    = 1,
  88.     kBSMPIDeviceMfrRecognized    = 2,
  89.     kBSMPIDeviceModelRecognized    = 3,
  90.     kBSMPIDeviceMediaRecognized    = 4
  91. };
  92.  
  93. typedef UInt32 BSMPIConfidenceLevel;
  94. /*
  95. ******************************************************************************
  96.  
  97.     Mapping Plug-In Level of Confidence values
  98.     
  99.  *****************************************************************************
  100. */
  101.  
  102. enum {
  103.     kBSCPIDeviceNotSupported    = 0,
  104.     kBSCPIDeviceTypeRecognized    = 1,
  105.     kBSCPIDeviceMfrRecognized    = 2,
  106.     kBSCPIDeviceModelRecognized    = 3
  107. };
  108.  
  109. typedef UInt32 BSCPIConfidenceLevel;
  110. /*
  111. ******************************************************************************
  112.  
  113.     Plug In Version - this tracks the revision of the plug-in interface and
  114.         should be placed in the version field of the plug-in interface structure
  115.     
  116.  *****************************************************************************
  117. */
  118.  
  119. enum {
  120.     kBSPlugInInterfaceVersion    = 0x02011996
  121. };
  122.  
  123. /*
  124. ******************************************************************************
  125.  
  126.     BSIOStatus values
  127.     
  128.  *****************************************************************************
  129. */
  130.  
  131. enum {
  132.     kBSIOCompleted                = 1,
  133.     kBSIOContinuing                = 2,
  134.     kBSIOFailed                    = 3,
  135.     kBSIONotStarted                = 4
  136. };
  137.  
  138. typedef UInt32 BSIOStatus;
  139. /*
  140. ******************************************************************************
  141.  *******************************************************************************
  142.  *******************************************************************************
  143.  
  144.     Types
  145.     
  146.  *******************************************************************************
  147.  *******************************************************************************
  148.  *****************************************************************************
  149. */
  150. typedef void *BSStorePtr;
  151. typedef void *BSContainerPtr;
  152. typedef void *BSIORequestBlockPtr;
  153. typedef OSStatus BSIOErrors;
  154. /*
  155. ******************************************************************************
  156.     BSErrorList:  another structure to manage I/O success/failure.
  157.  
  158.     BSErrorList data structure allows a Mapping Plug-In to keep track of the
  159.     current state of each transfer request sent to it by the Block Storage client.  If transfers complete
  160.     successfully, a pointer 0 is returned.  If an error occurs, a linked list (?) of these data structures
  161.     is returned specifying the exact state of each transfer request.
  162.  
  163.     startingBlock:        The initial transfer block of this fragment of the request
  164.     blockCount:            The number of blocks to be transfered including the startingBlock
  165.     status:                A constant representing the final state of the transfer of the blocks:
  166.                                  kIONotStarted:                No processing was begun on these blocks
  167.                                 kIOStarted:                    The BS Plug-In began to process the blocks
  168.                                 kIOToFamily:                The request was sent to the device family
  169.                                 kIOComplete:                The request completed normally
  170.                                  kIOFailed:                    The request failed to complete execution
  171.     error:                The exact error, if any
  172.     xferID:                An index representing which request of a multiple-request I/O this is
  173.      next:                A pointer to the next data structure (could be eliminated in favor of indices)
  174.  *****************************************************************************
  175. */
  176. struct BSErrorList {
  177.     BSByteCount                     startingBlock;
  178.     BSByteCount                     length;
  179.     UInt32                             status;
  180.     BSIOErrors                         error;
  181.     ItemCount                         xferID;
  182.     struct BSErrorList *            next;
  183. };
  184. typedef struct BSErrorList BSErrorList;
  185.  
  186. typedef BSErrorList *BSErrorListPtr;
  187. /*
  188. ****************************************************************************
  189.  
  190.     BSStoreMPIComponent describes a component of a Store.  A component may
  191.     be an external device or another Store.  This is the internal form of
  192.     BSStoreComponent.
  193.     
  194.  ***************************************************************************
  195. */
  196. struct BSStoreMPIComponent {
  197.     BSComponentType                 componentType;
  198.     BSByteCount                     startingOffset;                /* Where in the Store this */
  199.                                                                 /* component will be placed */
  200.     RegEntryRef                     sourceNode;                    /* Physical components */
  201.     BSStorePtr                         srcStore;                    /* Logical components */
  202.     BSPartitionDescriptor             partitionInfo;                /* Logical components */
  203. };
  204. typedef struct BSStoreMPIComponent BSStoreMPIComponent;
  205.  
  206. typedef BSStoreMPIComponent *BSStoreMPIComponentPtr;
  207. /*
  208. ******************************************************************************
  209.  
  210.     BSStoreMPIInfo - Information about the Store that the Mapping Plug-in can
  211.         provide
  212.         
  213.  *****************************************************************************
  214. */
  215. struct BSStoreMPIInfo {
  216.     BSAccessibilityState             curState;
  217.     BSByteCount                     storeSize;
  218.     BSByteCount                     readBlockSize;                /* minimum read size & granularity */
  219.     BSByteCount                     writeBlockSize;                /* minimum write size & granularity */
  220.  
  221.     Boolean                         isEjectable;
  222.     Boolean                         isWriteable;
  223.     Boolean                         hasAutoEjectHardware;
  224.     Boolean                         isFormattable;
  225.  
  226.     Boolean                         isPartitionable;
  227.     Boolean                         isFilesystem;
  228.     Boolean                         reserved1;
  229.     Boolean                         reserved2;
  230.  
  231.     BSStoreFormatInfo                 curFormat;
  232.  
  233.     BSStoreFormatInfo                 possibleFormats[8];
  234.  
  235.     char                             name[48];
  236. };
  237. typedef struct BSStoreMPIInfo BSStoreMPIInfo;
  238.  
  239. typedef BSStoreMPIInfo *BSStoreMPIInfoPtr;
  240. /*
  241. ******************************************************************************
  242.  
  243.     BSStorePPIInfo - Information about the Store that the Partitioning Plug-in 
  244.         can provide
  245.         
  246.  *****************************************************************************
  247. */
  248. struct BSStorePPIInfo {
  249.     ItemCount                         numPartitions;
  250.     ItemCount                         maxPartitions;
  251. };
  252. typedef struct BSStorePPIInfo BSStorePPIInfo;
  253.  
  254. typedef BSStorePPIInfo *BSStorePPIInfoPtr;
  255. /*
  256. ******************************************************************************
  257.  
  258.     BSContainerPIInfo - Information about the Container that the Container
  259.         Plug-in can provide
  260.         
  261.  *****************************************************************************
  262. */
  263. struct BSContainerPIInfo {
  264.     ItemCount                         numChildren;
  265.     Boolean                         isEjectable;
  266.  
  267. };
  268. typedef struct BSContainerPIInfo BSContainerPIInfo;
  269.  
  270. typedef BSContainerPIInfo *BSContainerPIInfoPtr;
  271. /*
  272. ******************************************************************************
  273.  *******************************************************************************
  274.  *******************************************************************************
  275.  
  276.     Plug-In Interface Functions
  277.     
  278.  *******************************************************************************
  279.  *******************************************************************************
  280.  *****************************************************************************
  281. */
  282. /*
  283. ******************************************************************************
  284.  *******************************************************************************
  285.  
  286.     Mapping Plug-In Interface
  287.     
  288.  *******************************************************************************
  289.  *****************************************************************************
  290. */
  291. /*
  292. ******************************************************************************
  293.     BSMappingPIExamine - Plug-in's opportunity to examine a device and determine
  294.             if it is an appropriate plug-in for it
  295.     
  296.     Inputs:        examineStore - a pointer to the in-process Store to be examined
  297.     
  298.     Outputs:    confidence - level of confidence the plug-in has that the plugin
  299.                 is the correct one
  300.     
  301.     Returns:    E_BSSuccess if no errors happened examining the device.  
  302.                 If an error happened, the error received from the other family is
  303.                 returned
  304.  *****************************************************************************
  305. */
  306. typedef OSStatus (*BSMappingPIExamine)(BSStorePtr examineStore, BSMPIConfidenceLevel *confidence);
  307. /*
  308. ******************************************************************************
  309.  
  310.     BSMappingPIInit - Plug-in's initialization routine.  Called when plug-in
  311.             is selected for a Store.  Plug-in's opportunity to initialize
  312.             device, allocate data structures, etc.
  313.     
  314.     Inputs:        initStore - a pointer to the Store this plug-in will be attached
  315.                     to
  316.     Outputs:    curState - the current state of the media
  317.     
  318.     Returns:    E_BSSuccess if successful
  319.     
  320.  *****************************************************************************
  321. */
  322. typedef OSStatus (*BSMappingPIInit)(BSStorePtr initStore);
  323. /*
  324. ******************************************************************************
  325.  
  326.     BSMappingPICleanup - Plug-in's dispose routine.  Called when Store is
  327.             being disposed of.  Should dispose of any memory or data structures
  328.             held for this Store, finalize all I/O for Store
  329.     
  330.     Inputs:        cleanupStore - Store that is being disposed of
  331.     
  332.     Outputs:    <none>
  333.     
  334.     Returns:    E_BSSuccess if successful
  335.     
  336.  *****************************************************************************
  337. */
  338. typedef OSStatus (*BSMappingPICleanup)(BSStorePtr cleanupStore);
  339. /*
  340. ******************************************************************************
  341.     BSMappingPIIO - Plug-in's input/output routine
  342.     
  343.     Inputs:        ioStore - the Store on which IO is to be performed
  344.                 blocks - descriptor of the blocks to do IO on
  345.                 memory - descriptor of the memory to do IO on (memory has been prepared)
  346.                 parentRequest - the request this request is being made on behalf of
  347.                 options - read/write
  348.     
  349.     Outputs:    errors - where exactly the errors occured, if any
  350.     
  351.     Returns:    kBSIOContinuing if IO was started successfully and the I/O
  352.                     completion routine still needs to be called
  353.                 kBSIOCompleted if IO was completed and no further action is
  354.                     necessary
  355.                 kBSIOFailed if IO failed for some reason
  356.                 kBSIONotStarted if the IO could not be started
  357.  *****************************************************************************
  358. */
  359. typedef BSIOStatus (*BSMappingPIIO)(BSStorePtr ioStore, BSBlockListDescriptorRef blocks, MemListDescriptorRef memory, BSIORequestBlockPtr parentRequest, OptionBits options, BSErrorList **errors);
  360. /*
  361. ******************************************************************************
  362.     BSMappingPIFlush - flush plug-in's cached data (if any)
  363.             BSMappingPIFlush flushes the plug-in's cached data.  It is called
  364.             in a similar fashion to an I/O request.  BSStoreRW may be used
  365.             as may BSStoreFlush.
  366.     
  367.     Inputs:        flushStore - the Store on which flush is to be performed
  368.                 parentRequest - the request this request is being made on behalf of
  369.     
  370.     Outputs:    errors - where exactly the errors occured, if any
  371.     
  372.     Returns:    kBSIOContinuing if IO was started successfully and the I/O
  373.                     completion routine still needs to be called
  374.                 kBSIOCompleted if IO was completed and no further action is
  375.                     necessary
  376.                 kBSIOFailed if IO failed for some reason
  377.                 kBSIONotStarted if the IO could not be started
  378.  *****************************************************************************
  379. */
  380. typedef BSIOStatus (*BSMappingPIFlush)(BSStorePtr ioStore, BSIORequestBlockPtr parentRequest, BSErrorList **errors);
  381. /*
  382. ******************************************************************************
  383.     BSMappingPIAddComponent - Notifies Plug-in about new components to be added
  384.         to it
  385.     
  386.     Inputs:        destStore - the Store the blocks are to be mapped into
  387.                 newComponent - the new Component to be mapped in
  388.     
  389.     Outputs:    storeNewInfo - the new information about the Store
  390.  
  391.     
  392.     Returns:    E_BSSuccess if successful
  393.                 E_BSMPITooManyMappings if no more mappings can be handled
  394.                 E_BSMPIOutOfStoreBounds if the start of the destination blocks 
  395.                     would cause a gap in the Store
  396.     
  397.  *****************************************************************************
  398. */
  399. typedef OSStatus (*BSMappingPIAddComponent)(BSStorePtr destStore, BSStoreMPIComponent *newComponent, BSStoreInfo *storeNewInfo);
  400. /*
  401. ******************************************************************************
  402.     BSMappingPIGoToState - Requests plug-in to take Store to the specified 
  403.             accessibility state.  
  404.     
  405.     Inputs:        theStore - Store to take to the state
  406.                 gotoState - what state to go to (possible states defined above)
  407.                                 
  408.     
  409.     Outputs:    <none>
  410.  
  411.     Returns:    E_BSSuccess if successful
  412.     
  413.  *****************************************************************************
  414. */
  415. typedef OSStatus (*BSMappingPIGoToState)(BSStorePtr theStore, BSAccessibilityState gotoState);
  416. /*
  417. ******************************************************************************
  418.     BSMappingPIFormatMedia - tells plug-in to do a low-level format of the media
  419.     
  420.     Inputs:        formatStore - Store to format
  421.     
  422.     Outputs:    <none>
  423.     
  424.     Returns:    E_BSSuccessful if successful
  425.     
  426.  *****************************************************************************
  427. */
  428. typedef OSStatus (*BSMappingPIFormatMedia)(BSStorePtr formatStore, BSFormatIndex formatType);
  429. /*
  430. ******************************************************************************
  431.     BSMappingPIGetInfo - gets information about the device and the plug-in
  432.     
  433.     Inputs:        formatStore - Store to format
  434.     
  435.     Outputs:    info - the filled in information
  436.     
  437.     Returns:    E_BSSuccessful if successful
  438.     
  439.  *****************************************************************************
  440. */
  441. typedef OSStatus (*BSMappingPIGetInfo)(BSStorePtr infoStore, BSStoreMPIInfo *info);
  442. /*
  443. ******************************************************************************
  444.     BSMappingIOCompletion - I/O completion routine for a mapping plug-in
  445.     
  446.     Inputs:        theStore:  - A pointer to the Store in question
  447.                 finishedPrivateData - A pointer to the private data the Mapping 
  448.                     plug-in associated with this I/O
  449.                 returnedBSErrorList - A pointer to a BSErrorList if the 
  450.                     triggering event came from another BS plug-in
  451.                 returnedStatus - The OSStatus returned by the other family or 
  452.                     plug-in that was called
  453.     Outputs:    errorListPtrPtr - A pointer to a pointer to a BSErrorList.  
  454.                     The BSErrorList is allocated and filled in by the completion 
  455.                     routine if the I/O has failed.  It should be allocated using 
  456.                     BSErrorListAllocate and will be deallocated by the family code.
  457.     
  458.     Returns:    E_BSSuccess if successful
  459.  
  460.  *****************************************************************************
  461. */
  462. typedef OSStatus (*BSMappingIOCompletion)(BSStorePtr theStore, void *finishedPrivateData, BSErrorListPtr returnedBSErrorList, OSStatus returnedStatus, BSErrorListPtr *errorListPtrPtr);
  463. struct BlockStoragePlugInInfo {
  464.     UInt32                             version;
  465.     UInt32                             reserved1;
  466.     UInt32                             reserved2;
  467.     UInt32                             reserved3;
  468. };
  469. typedef struct BlockStoragePlugInInfo BlockStoragePlugInInfo;
  470.  
  471. struct BSStoreMappingOps {
  472.     BlockStoragePlugInInfo             header;
  473.     BSMappingPIExamine                 DeviceExamine;
  474.     BSMappingPIInit                 Init;
  475.     BSMappingPICleanup                 Cleanup;
  476.     BSMappingPIIO                     IO;
  477.     BSMappingPIFlush                 Flush;
  478.     BSMappingPIAddComponent         AddComponent;
  479.     BSMappingPIGoToState             GotoState;
  480.     BSMappingPIFormatMedia             Format;
  481.     BSMappingPIGetInfo                 GetInfo;
  482.     BSMappingIOCompletion             ioCompletion;
  483. };
  484. typedef struct BSStoreMappingOps BSStoreMappingOps;
  485.  
  486. typedef BSStoreMappingOps *BSStoreMappingOpsPtr;
  487. /*
  488. ******************************************************************************
  489.  
  490.     BSMPIBackgroundTask - a background task entry point for a Mapping plug-in.
  491.             BSMPIStartBackgroundTask may be used by the Mapping plug-in to
  492.             start one of these.  The task will be automatically terminated
  493.             after the Cleanup routine is executed
  494.     
  495.     Inputs:        theStore - the Store this is running for
  496.                 theArg - the argument passed to BSMPIStartBackgroundTask
  497.                 
  498.     Outputs:    <none>
  499.     
  500.     Returns:    Errors are ignored but will be logged.
  501.  *****************************************************************************
  502. */
  503. typedef OSStatus (*BSMPIBackgroundTask)(BSStorePtr theStore, void *theArg);
  504. /*
  505. ******************************************************************************
  506.  *******************************************************************************
  507.  
  508.     Partitioning Plug-In Interface
  509.     
  510.  *******************************************************************************
  511.  *****************************************************************************
  512. */
  513. /*
  514. ******************************************************************************
  515.     BSPartitioningPIExamine - Plug-in's opportunity to examine a Store and
  516.             determine if it's the right plug-in for it
  517.     
  518.     Inputs:        readStoreConn - a connection to the Store to be examined
  519.     
  520.     Outputs:    certainty - 0 if the plug-in did not recognize the partition
  521.                     map format
  522.                 otherwise the number of bytes read
  523.     
  524.     Returns:    E_BSSuccess if no errors occured
  525.                 E_BSPPIOutOfResources if memory or other resource couldn't
  526.                     be allocated
  527.                 otherwise the Block Storage error from the I/O
  528.     
  529.  *****************************************************************************
  530. */
  531. typedef OSStatus (*BSPartitioningPIExamine)(BSStoreConnID readStoreConn, UInt32 *certainty);
  532. /*
  533. ******************************************************************************
  534.     BSPartitioningPIInit - Plug-in's initialization routine.  Called when 
  535.             plug-in is selected for a Store.  Plug-in's opportunity to 
  536.             initialize device, allocate data structures, etc.
  537.     
  538.     Inputs:        initStore - pointer to the Store the plug-in is being attached to
  539.                     
  540.     Outputs:    <none>
  541.     
  542.     Returns:    E_BSSuccess if successful
  543.     
  544.  *****************************************************************************
  545. */
  546. typedef OSStatus (*BSPartitioningPIInit)(BSStorePtr initStore);
  547. /*
  548. ******************************************************************************
  549.  
  550.     BSPartitioningPICleanup - Plug-in's dispose routine.  Called when Store is
  551.             being disposed of.  Should dispose of any memory or data structures
  552.             held for this Store and flush the partition map if necessary
  553.     
  554.     Inputs:        cleanupStore - Store that is being disposed of
  555.     
  556.     Outputs:    <none>
  557.     
  558.     Returns:    E_BSSuccess if successful
  559.     
  560.  *****************************************************************************
  561. */
  562. typedef void (*BSPartitioningPICleanup)(BSStorePtr cleanupStore);
  563. /*
  564. ******************************************************************************
  565.     BSPartitioningPIInitializeMap - lays down a new partition map on a Store (plug-in has
  566.             already been attached)
  567.     
  568.     Inputs:        initStore - the Store to be initialized
  569.     
  570.     Outputs:    <none>
  571.     
  572.     Returns:    E_BSSuccess if successful
  573.                 otherwise, Block Storage error if I/O fails
  574.     
  575.  *****************************************************************************
  576. */
  577. typedef OSStatus (*BSPartitioningPIInitializeMap)(BSStorePtr initStore);
  578. /*
  579. ******************************************************************************
  580.     BSPartitioningPIGetInfo - Gets information about the partition map and the
  581.         partitioning plug-in
  582.     
  583.     Inputs:        store - the Store to read from
  584.     
  585.     Outputs:    info - the filled in information
  586.     
  587.     Returns:    E_BSSuccess if successful
  588.     
  589.  *****************************************************************************
  590. */
  591. typedef OSStatus (*BSPartitioningPIGetInfo)(BSStorePtr store, BSStorePPIInfo *info);
  592. /*
  593. ******************************************************************************
  594.     BSPartitioningPIGetEntry - Get a particular partition map entry
  595.     
  596.     Inputs:        readStore - the Store
  597.                 entryNum - which entry to read
  598.                 
  599.     Outputs:    retEntry - pointer to a BSPartitionDescriptor that's filled in
  600.                     with the entry
  601.     
  602.     Returns:    E_BSSuccess if successful
  603.                 E_BSPPIPartitionNonExistant if that entry does not exist
  604.                 other Block Storage error if I/O problem
  605.     
  606.  *****************************************************************************
  607. */
  608. typedef OSStatus (*BSPartitioningPIGetEntry)(BSStorePtr readStore, ItemCount entryNum, BSPartitionDescriptor *retEntry);
  609. /*
  610. ******************************************************************************
  611.     BSPartitioningSetEntry - Sets the information in a particular partition map
  612.             entry
  613.     
  614.     Inputs:        
  615.     
  616.     Outputs:    
  617.     
  618.     Returns:    
  619.     
  620.  *****************************************************************************
  621. */
  622. typedef OSStatus (*BSPartitioningPISetEntry)(BSStorePtr store, ItemCount partitionNum, BSPartitionDescriptor *partitionInfo);
  623. struct BSStorePartitioningOps {
  624.     BlockStoragePlugInInfo             header;
  625.     BSPartitioningPIExamine         Examine;
  626.     BSPartitioningPIInit             Init;
  627.     BSPartitioningPICleanup         Cleanup;
  628.     BSPartitioningPIInitializeMap     InitializeMap;
  629.     BSPartitioningPIGetInfo         GetInfo;
  630.     BSPartitioningPIGetEntry         GetEntry;
  631.     BSPartitioningPISetEntry         SetEntry;
  632. };
  633. typedef struct BSStorePartitioningOps BSStorePartitioningOps;
  634.  
  635. typedef BSStorePartitioningOps *BSStorePartitioningOpsPtr;
  636. /*
  637. ******************************************************************************
  638.  *******************************************************************************
  639.  
  640.     Container Plug-In Interface
  641.     
  642.  *******************************************************************************
  643.  *****************************************************************************
  644. */
  645. /*
  646. ******************************************************************************
  647.  
  648.     BSContainerPIExamine - Called to allow the Container plug-in to verify
  649.         that it is correct for the Container
  650.  
  651.     Inputs:        initContainer - the Container in question    
  652.  
  653.     Outputs:    levelOfConfidence - how confident the plug-in is that it is the
  654.                     correct one
  655.  
  656.     Returns:    E_BSSuccess if successful
  657.  
  658.  *****************************************************************************
  659. */
  660. typedef OSStatus (*BSContainerPIExamine)(BSContainerPtr initContainer, BSCPIConfidenceLevel *levelOfConfidence);
  661. /*
  662. ******************************************************************************
  663.  
  664.     BSContainerPIInit - Plug-in's initialization routine.  Called when 
  665.         plug-in is selected for a Container.  Plug-in's opportunity to 
  666.         initialize device, allocate data structures, etc.
  667.  
  668.     Inputs:        initContainer - a pointer to the Container this plug-in will 
  669.                 be attached to
  670.     Outputs:    info - information about the new Container
  671.                 backgroundTask - if true, the BackgroundTask entry point will
  672.                     be invoked in its own private task.
  673.     
  674.     Returns:    E_BSSuccess if successful
  675.     
  676.  *****************************************************************************
  677. */
  678. typedef OSStatus (*BSContainerPIInit)(BSContainerPtr initContainer, BSContainerPIInfo *info, Boolean *backgroundTask);
  679. /*
  680. ******************************************************************************
  681.  
  682.     BSContainerPICleanup - cleans up plug-in state
  683.  
  684.     Inputs:        container - the Container to clean up for
  685.  
  686.     Outputs:    <none>
  687.  
  688.     Returns:    E_BSSuccess if successful
  689.  
  690.  *****************************************************************************
  691. */
  692. typedef OSStatus (*BSContainerPICleanup)(BSContainerPtr container);
  693. /*
  694. ******************************************************************************
  695.  
  696.     BSContainerPIGoToState - Tells the Container to go the specified state
  697.  
  698.     Inputs:        container - the Container to take to the state
  699.                 accessState - the state to go to
  700.  
  701.     Outputs:    <none>
  702.  
  703.     Returns:    E_BSSuccess if successful
  704.  
  705.  *****************************************************************************
  706. */
  707. typedef OSStatus (*BSContainerPIGoToState)(BSContainerPtr container, UInt32 accessState);
  708. /*
  709. ******************************************************************************
  710.  
  711.     BSContainerPIAddContainer - Informs the Container of a new sub-Container
  712.         being added
  713.  
  714.     Inputs:        destContainer - the Container we're adding to
  715.                 addedContainer - the Container being added
  716.  
  717.     Outputs:    <none>
  718.  
  719.     Returns:    E_BSSuccess if successful
  720.  
  721.  *****************************************************************************
  722. */
  723. typedef OSStatus (*BSContainerPIAddContainer)(BSContainerPtr destContainer, BSContainerPtr addedContainer);
  724. /*
  725. ******************************************************************************
  726.  
  727.     BSContainerPIGetInfo - Gets information about a Container
  728.  
  729.     Inputs:        infoContainer - the Container to get information about
  730.  
  731.     Outputs:    info - the filled in information buffer
  732.  
  733.     Returns:    E_BSSuccess if successful
  734.  
  735.  *****************************************************************************
  736. */
  737. typedef OSStatus (*BSContainerPIGetInfo)(BSContainerPtr infoContainer, BSContainerPIInfo *info);
  738. /*
  739. ******************************************************************************
  740.  
  741.     BSContainerPIBackgroundTask - an optional entry point that will be executed
  742.         within its own task context if the backgroundTask flag is set on exit
  743.         from the Container Plug-in's init routine
  744.     
  745.     Inputs:        container - the Container the Background Task is being invoked 
  746.                         on behalf of
  747.     
  748.     Outputs:    <none>
  749.     
  750.     Returns:    E_BSSuccessful if successful
  751.     
  752.  *****************************************************************************
  753. */
  754. typedef OSStatus (*BSContainerPIBackgroundTask)(BSContainerPtr container);
  755. struct BSContainerPolicyOps {
  756.     BlockStoragePlugInInfo             header;
  757.     BSContainerPIExamine             Examine;
  758.     BSContainerPIInit                 Init;
  759.     BSContainerPICleanup             Cleanup;
  760.     BSContainerPIGoToState             GoToState;
  761.     BSContainerPIAddContainer         AddContainer;
  762.     BSContainerPIGetInfo             GetInfo;
  763.     BSContainerPIBackgroundTask     BackgroundTask;
  764. };
  765. typedef struct BSContainerPolicyOps BSContainerPolicyOps;
  766.  
  767. typedef BSContainerPolicyOps *BSContainerPolicyOpsPtr;
  768. /*
  769. ******************************************************************************
  770.  
  771.     BSCPIBackgroundTask - a background task entry point for a Container plug-in.
  772.             BSCPIStartBackgroundTask may be used by the Container plug-in to
  773.             start one of these.  The task will be automatically terminated
  774.             after the Cleanup routine is executed
  775.     
  776.     Inputs:        theContainer - the Container this is running for
  777.                 theArg - the argument passed to BSMPIStartBackgroundTask
  778.                 
  779.     Outputs:    <none>
  780.     
  781.     Returns:    Errors are ignored but will be logged.
  782.  *****************************************************************************
  783. */
  784. typedef OSStatus (*BSCPIBackgroundTask)(BSContainerPtr theContainer, void *theArg);
  785. /*
  786. ******************************************************************************
  787.  *******************************************************************************
  788.  *******************************************************************************
  789.  
  790.     Block Storage Family Services
  791.     
  792.  *******************************************************************************
  793.  *******************************************************************************
  794.  *****************************************************************************
  795. */
  796. /*
  797. ******************************************************************************
  798.     BSStoreRW - Request I/O from another Store.  Used by Mapping Plug-ins.
  799.                 Not for use by Partitioning Plug-ins!!
  800.     
  801.     Inputs:        rwStore - the Store to do I/O with
  802.                 blocks - the blocks for the transfer
  803.                 memory - the memory for the transfer
  804.                 parentRequest - the BSIORequestPtr that the requestor was called
  805.                     with
  806.                 privateData - pointer to be given to the completion routine
  807.                     when it is called
  808.                 options - read/write
  809.                 
  810.     Outputs:    errors - where errors occurred, if any occurred
  811.     
  812.     Returns:    return code from other plug-in
  813.     
  814.  *****************************************************************************
  815. */
  816. extern BSIOStatus BSStoreRW(BSStorePtr rwStore, BSBlockListDescriptorRef blocks, MemListDescriptorRef memory, BSIORequestBlockPtr parentRequest, void *privateData, OptionBits options, BSErrorListPtr *errors);
  817.  
  818. /*
  819. ******************************************************************************
  820.     BSStoreFlush - Request another Store to flush its caches.  Used by Mapping Plug-ins.
  821.                 Not for use by Partitioning Plug-ins!!
  822.     
  823.     Inputs:        flushStore - the Store to flush
  824.                 parentRequest - the BSIORequestPtr that the requestor was called
  825.                     with
  826.                 privateData - pointer to be given to the completion routine
  827.                     when it is called
  828.                 
  829.     Outputs:    errors - where errors occurred, if any occurred
  830.     
  831.     Returns:    return code from other plug-in
  832.     
  833.  *****************************************************************************
  834. */
  835. extern BSIOStatus BSStoreFlush(BSStorePtr flushStore, BSIORequestBlockPtr parentRequest, void *privateData, BSErrorListPtr *errors);
  836.  
  837. /*
  838. ******************************************************************************
  839.     BSTrackOtherFamilyRequest  - informs the Block Storage family code what routine 
  840.         should be called when the other I/O family the request is being passed to 
  841.         notifies the Block Storage family of its completion.  The Mapping plug-in's
  842.         ioCompletion routine will be called when the notification of the request
  843.         completion is received.
  844.  
  845.     Inputs:        ioStore - Store I/O is taking place in
  846.                 curRequest - BSIORequestBlock for which this I/O is taking place.
  847.                         This was the BSIORequestBlockPtr passed into the R/W 
  848.                         routine.
  849.                 privateData - Private data to be passed back when the completion routine
  850.                         is called.
  851.                 retNotify - Pointer to a kernel notification structure that will
  852.                         be filled in by BSTrackOtherFamilyRequest to be given
  853.                         to the other family in the async API call
  854.     
  855.     Outputs:    <none>
  856.     
  857.     Returns:    E_BSSuccess if able to track request
  858.  
  859.  *****************************************************************************
  860. */
  861. extern OSStatus BSTrackOtherFamilyRequest(BSStorePtr ioStore, BSIORequestBlockPtr curRequest, void *privateData, KernelNotificationPtr retNotify);
  862.  
  863. /*
  864. ******************************************************************************
  865.     BSMPIStartBackgroundTask - starts a background task for a Mapping Plug-in.
  866.         The task will be terminated after the Cleanup routines for the Plug-in
  867.         is called for this Store.
  868.     
  869.     Inputs:        store - the Store the background task is being started for
  870.                 backgroundTask - the function to start
  871.                 arg - the argument to be passed to the function
  872.     
  873.     Outputs:    taskID - the task ID of the new task
  874.     
  875.     Returns:    E_BSSuccess if successful
  876.  
  877.  *****************************************************************************
  878. */
  879. extern OSStatus BSMPIStartBackgroundTask(BSStorePtr store, BSMPIBackgroundTask backgroundTask, void *arg, TaskID *taskID);
  880.  
  881. /*
  882. ******************************************************************************
  883.     BSCPIStartBackgroundTask - starts a background task for a Container Plug-in.
  884.         The task will be terminated after the Cleanup routines for the Plug-in
  885.         is called for this Container.
  886.     
  887.     Inputs:        container - the Container the background task is being started for
  888.                 backgroundTask - the function to start
  889.                 arg - the argument to be passed to the function
  890.     
  891.     Outputs:    taskID - the task ID of the new task
  892.     
  893.     Returns:    E_BSSuccess if successful
  894.  
  895.  *****************************************************************************
  896. */
  897. extern OSStatus BSCPIStartBackgroundTask(BSContainerPtr container, BSCPIBackgroundTask backgroundTask, void *arg, TaskID *taskID);
  898.  
  899. /*
  900. ******************************************************************************
  901.  *******************************************************************************
  902.  
  903.     Store Accessor functions
  904.     
  905.  *******************************************************************************
  906.  *****************************************************************************
  907. */
  908. /*
  909. ******************************************************************************
  910.     BSGetMappingPIPrivateData - retrieves the Mapping Plug-in's private data
  911.         from a Store
  912.     
  913.     Inputs:        accessStore - the Store to retrieve the data from
  914.     
  915.     Outputs:    <none>
  916.     
  917.     Returns:    pointer to data
  918.  
  919.  *****************************************************************************
  920. */
  921. extern void *BSGetMappingPIPrivateData(BSStorePtr accessStore);
  922.  
  923. /*
  924. ******************************************************************************
  925.     BSSetMappingPIPrivateData - sets the Mapping Plug-in's private data
  926.         for a Store
  927.     
  928.     Inputs:        accessStore - the Store to set the data in
  929.                 privateData - pointer to the data
  930.     
  931.     Outputs:    <none>
  932.     
  933.     Returns:    <none>
  934.  
  935.  *****************************************************************************
  936. */
  937. extern void BSSetMappingPIPrivateData(BSStorePtr accessStore, void *privateData);
  938.  
  939. /*
  940. ******************************************************************************
  941.     BSGetPartitioningPIPrivateData - retrieves the Partitioning Plug-in's private 
  942.         data from a Store
  943.     
  944.     Inputs:        accessStore - the Store to retrieve the data from
  945.     
  946.     Outputs:    <none>
  947.     
  948.     Returns:    pointer to data
  949.  
  950.  *****************************************************************************
  951. */
  952. extern void *BSGetPartitioningPIPrivateData(BSStorePtr accessStore);
  953.  
  954. /*
  955. ******************************************************************************
  956.     BSSetPartitioningPIPrivateData - sets the Partitioning Plug-in's private data
  957.         for a Store
  958.     
  959.     Inputs:        accessStore - the Store to set the data in
  960.                 privateData - pointer to the data
  961.     
  962.     Outputs:    <none>
  963.     
  964.     Returns:    <none>
  965.  
  966.  *****************************************************************************
  967. */
  968. extern void BSSetPartitioningPIPrivateData(BSStorePtr accessStore, void *privateData);
  969.  
  970. /*
  971. ******************************************************************************
  972.     BSStoreGetNumComponents - Gets the number of component Stores or Devices 
  973.         that have been put together into this Store
  974.     
  975.     Inputs:        accessStore - the Store to get the number of components from
  976.     
  977.     Outputs:    <none>
  978.     
  979.     Returns:    number of components
  980.  
  981.  *****************************************************************************
  982. */
  983. extern ItemCount BSStoreGetNumComponents(BSStorePtr accessStore);
  984.  
  985. /*
  986. ******************************************************************************
  987.     BSStoreGetComponents - Gets the information about a particular component
  988.         of a Store
  989.     
  990.     Inputs:        accessStore - the Store to get the number of components from
  991.                 componentNum - which component to return
  992.     
  993.     Outputs:    component - the BSStoreComponent buffer that is filled in
  994.     
  995.     Returns:    E_BSSuccess if no problems
  996.  
  997.  *****************************************************************************
  998. */
  999. extern OSStatus BSStoreGetComponent(BSStorePtr accessStore, ItemCount componentNum, BSStoreMPIComponentPtr component);
  1000.  
  1001. /*
  1002. ******************************************************************************
  1003.     BSStoreSetNumPartitions - sets the number of partitions in the Store
  1004.     
  1005.     Inputs:        accessStore - the Store to get the number of components from
  1006.                 numPartitions - the new partition count
  1007.     
  1008.     Outputs:    <none>
  1009.     
  1010.     Returns:    <none>
  1011.  
  1012.  *****************************************************************************
  1013. */
  1014. extern void BSStoreSetNumPartitions(BSStorePtr accessStore, ItemCount numPartitions);
  1015.  
  1016. /*
  1017. ******************************************************************************
  1018.     BSStoreGetPPIConnection - Gets the Store connection for the partitioning 
  1019.         plug-ins
  1020.     
  1021.     Inputs:        accessStore - the Store to get connection from
  1022.     
  1023.     Outputs:    <none>
  1024.     
  1025.     Returns:    Connection to the Store (kInvalidID if none)
  1026.  
  1027.  *****************************************************************************
  1028. */
  1029. extern BSStoreConnID BSStoreGetPPIConnection(BSStorePtr accessStore);
  1030.  
  1031. /*
  1032. ******************************************************************************
  1033.     BSStoreGetAccessibilityState - Gets the current accessibility state of the Store
  1034.     
  1035.     Inputs:        accessStore - the Store to get connection from
  1036.     
  1037.     Outputs:    <none>
  1038.     
  1039.     Returns:    Store's state
  1040.  
  1041.  *****************************************************************************
  1042. */
  1043. extern BSAccessibilityState BSStoreGetAccessibilityState(BSStorePtr accessStore);
  1044.  
  1045. /*
  1046. ******************************************************************************
  1047.     BSStoreSetAccessibilityState - Sets the current accessibility state of the Store
  1048.     
  1049.     Inputs:        accessStore - the Store to get connection from
  1050.                 setState - the state to set the Store to
  1051.     
  1052.     Outputs:    <none>
  1053.     
  1054.     Returns:    <none>
  1055.  
  1056.  *****************************************************************************
  1057. */
  1058. extern void BSStoreSetAccessibilityState(BSStorePtr accessStore, BSAccessibilityState setState);
  1059.  
  1060. /*
  1061. ******************************************************************************
  1062.     BSStoreGetMPIInfo - Calls the GetInfo routine of the Mapping plug-in 
  1063.         attached to the Store
  1064.     
  1065.     Inputs:        accessStore - the Store to get connection from
  1066.                 info - a pointer to the buffer to put the returned info into
  1067.     
  1068.     Outputs:    <none>
  1069.     
  1070.     Returns:    <none>
  1071.  
  1072.  *****************************************************************************
  1073. */
  1074. extern OSStatus BSStoreGetMPIInfo(BSStorePtr accessStore, BSStoreMPIInfo *info);
  1075.  
  1076. /*
  1077. ******************************************************************************
  1078.     BSStoreGetPPIInfo - Calls the GetInfo routine of the Partitioning plug-in 
  1079.         attached to the Store
  1080.     
  1081.     Inputs:        accessStore - the Store to get connection from
  1082.                 info - a pointer to the buffer to put the returned info into
  1083.     
  1084.     Outputs:    <none>
  1085.     
  1086.     Returns:    <none>
  1087.  
  1088.  *****************************************************************************
  1089. */
  1090. extern OSStatus BSStoreGetPPIInfo(BSStorePtr accessStore, BSStorePPIInfo *info);
  1091.  
  1092. /*
  1093. ******************************************************************************
  1094.  
  1095.     BSMPINotifyFamilyStoreChangedState - called from a Mapping Plug-in (typically
  1096.         in the BackgroundTask) to inform the Block Storage Family of an 
  1097.         unexpected accessibility change, e.g. the media was removed or the disk
  1098.         spun down.
  1099.  
  1100.     Inputs:        changedStore - the Store that changed
  1101.                 newState - the state the Store is now in
  1102.                 
  1103.     Outputs:    <none>
  1104.  
  1105.     Returns:    E_BSSuccess if successful
  1106.  
  1107.  *****************************************************************************
  1108. */
  1109. extern OSStatus BSMPINotifyFamilyStoreChangedState(BSStorePtr changedStore, BSAccessibilityState newState);
  1110.  
  1111. /*
  1112. ******************************************************************************
  1113.  
  1114.     BSMPIRequestStoreStateChange - requests a state change of the Store.  This
  1115.         should be used, for example, if a device has an eject button that can
  1116.         be monitored by the Mapping Plug-in.  If the eject button is pressed
  1117.         BSMPIRequestStoreStateChange should be used to notify the Family that
  1118.         an eject has been requested and the Family can then notify clients and
  1119.         flush data to the media properly.  This call waits until permission is
  1120.         granted or denied by the Expert.  The GoToState call of the plug-in
  1121.         will be invoked before this calls returns if permission is granted.
  1122.  
  1123.     Inputs:        changeStore - the Store the state change will affect
  1124.                 requestedState - the state the Store is being requested to go to
  1125.  
  1126.     Outputs:    permission - true if permission was granted and the Store 
  1127.                     successfully went to the State requested.
  1128.  
  1129.     Returns:    E_BSSuccess if successful
  1130.  
  1131.  *****************************************************************************
  1132. */
  1133. extern OSStatus BSMPIRequestStoreStateChange(BSStorePtr changeStore, BSAccessibilityState requestedState, Boolean *permission);
  1134.  
  1135. /*
  1136. ******************************************************************************
  1137.  
  1138.     BSCPINotifyFamilyContainerChangedState - called from a Container Plug-in 
  1139.         (typically in the BackgroundTask) to inform the Block Storage Family of 
  1140.         an unexpected accessibility change, e.g. the media was removed.
  1141.  
  1142.     Inputs:        changedStore - the Store that changed
  1143.                 newState - the state the Store is now in
  1144.                 
  1145.     Outputs:    <none>
  1146.  
  1147.     Returns:    E_BSSuccess if successful
  1148.  
  1149.  *****************************************************************************
  1150. */
  1151. extern OSStatus BSCPINotifyFamilyContainerChangedState(BSContainerPtr changedContainer, BSAccessibilityState newState);
  1152.  
  1153. /*
  1154. ******************************************************************************
  1155.  
  1156.     BSCPIRequestContainerStateChange - requests a state change of the Container. 
  1157.         This should be used, for example, if a device has an eject button that 
  1158.         can be monitored by the Container Plug-in.  If the eject button is pressed
  1159.         BSCPIRequestStoreStateChange should be used to notify the Family that
  1160.         an eject has been requested and the Family can then notify clients and
  1161.         flush data to the media properly.  This call waits until permission is
  1162.         granted or denied by the Expert.  The GoToState call of the plug-in
  1163.         will be invoked before this calls returns if permission is granted.
  1164.  
  1165.     Inputs:        changeContainer - the Container the state change will affect
  1166.                 requestedState - the state the Container is being requested to go to
  1167.  
  1168.     Outputs:    permission - true if permission was granted and the Container 
  1169.                     successfully went to the State requested.
  1170.  
  1171.     Returns:    E_BSSuccess if successful
  1172.  
  1173.  *****************************************************************************
  1174. */
  1175. extern OSStatus BSCPIRequestContainerStateChange(BSStorePtr changeContainer, BSAccessibilityState requestedState, Boolean *permission);
  1176.  
  1177. #endif
  1178.  
  1179. #pragma options align=reset
  1180. #endif /* PRAGMA_ALIGN_SUPPORTED */
  1181.  
  1182. #if PRAGMA_IMPORT_SUPPORTED
  1183. #pragma import off
  1184. #endif
  1185.  
  1186. #ifdef __cplusplus
  1187. }
  1188. #endif
  1189.  
  1190. #endif /* __BLOCKSTORAGEPLUGIN__ */
  1191.  
  1192.